<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>db_codegen</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C API Reference" />
    <link rel="up" href="utilities.html" title="Appendix 1.  Berkeley DB Command Line Utilities" />
    <link rel="prev" href="db_checkpoint.html" title="db_checkpoint" />
    <link rel="next" href="db_deadlock.html" title="db_deadlock" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">db_codegen</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="db_checkpoint.html">Prev</a> </td>
          <th width="60%" align="center">Appendix 1. 
                Berkeley DB Command Line Utilities
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="db_deadlock.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="db_codegen"></a>db_codegen</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">db_codegen [-Vv] [-a c] [-i file] [-o file]  </pre>
      <p>
        The <span class="command"><strong>db_codegen</strong></span> utility generates application code to create and configure
        Berkeley DB database environments and databases based on a simple description language, and
        writes it to one or more output files. The generated code may need modification, in the case
        of complicated applications, but will usually significantly reduce the time required to
        create Berkeley DB applications.
    </p>
      <p>
        The options are as follows:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p>
                <span class="bold"><strong>-a</strong></span>
            </p>
            <p>
                Generate code for the specified API ("c" is the default).
            </p>
          </li>
          <li>
            <p>
                <span class="bold"><strong>-i</strong></span>
            </p>
            <p>
                Specify an input file; by default, stdin is used.
            </p>
          </li>
          <li>
            <p>
                <span class="bold"><strong>-o</strong></span>
            </p>
            <p>
                Specify an output file prefix; by default, "application" is used.
            </p>
          </li>
          <li>
            <p>
                <span class="bold"><strong>-V</strong></span>
            </p>
            <p>
                Write the library version number to the standard output, and exit.
            </p>
          </li>
          <li>
            <p>
                <span class="bold"><strong>-v</strong></span>
            </p>
            <p>
                Run in verbose mode.
            </p>
          </li>
        </ul>
      </div>
      <p>
        The <span class="command"><strong>db_codegen</strong></span> utility exits 0 on success, and &gt;0 if an error occurs.
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1713333"></a>C Language Specific Information</h3>
            </div>
          </div>
        </div>
        <p>
            By default, when the <span class="command"><strong>db_codegen</strong></span> utility generates C-language code,
            the output file is named "application.c". The output filename can be specified with
            <span class="bold"><strong>-o</strong></span> option.
        </p>
        <p>
            At the beginning of the output file is a list of public database environment 
            — <a class="link" href="env.html" title="Chapter 5.  The DB_ENV Handle">DB_ENV</a> — handles and database 
            — <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a> — handles, as specified by the description
            language. The database environment handle variables are named "XXX_dbenv", where "XXX"
            is the name of the environment in the input specification. For databases associated with
            a database environment, the database handle variables are named "XXX_YYY", where "XXX"
            is the name of the environment, and "YYY" is the name of the database. For standalone
            databases, the database handle variables are named "XXX", where "XXX" is the name of the
            database.
        </p>
        <p>
            There are two public functions in the output file: <code class="function">bdb_startup</code> and
            <code class="function">bdb_shutdown</code>. The bdb_startup function should be called to create
            and configure the database environments and databases, and the bdb_shutdown function
            should be called to gracefully shut down the environments and databases.
        </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1713742"></a>Specification Language</h3>
            </div>
          </div>
        </div>
        <p>
            The <span class="command"><strong>db_codegen</strong></span> utility uses a simple description language:
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    Lines in the input consist of white-space separated tokens.
                </p>
            </li>
            <li>
              <p>
                    Tokens are case-insensitive. 
                </p>
            </li>
            <li>
              <p>
                    Empty lines, and lines where the first non-space character is hash mark ("#")
                    are ignored. In addition, hash marks may appear in lines, in which case the
                    content of the line from the hash mark to the end of the line is ignored. 
                </p>
            </li>
          </ul>
        </div>
        <p>
            There are two top-level objects: "environment" and "database", which correspond to
            database environments and databases, respectively. These top-level objects can be
            associated with keywords to describe their configuration and relationships.
        </p>
        <p>
            For example, the following input would create two standalone databases:
        </p>
        <pre class="programlisting">    database data_one {
        type btree
    }
    database data_two {
        type btree
    } </pre>
        <p>
            In this case, there would be no <a class="link" href="env.html" title="Chapter 5.  The DB_ENV Handle">DB_ENV</a> handle, and 
            the public <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a> handles would be:
        </p>
        <pre class="programlisting">            DB      *data_one;
            DB      *data_two; </pre>
        <p>
            For example, the following input would create a database environment which contains
            three databases:
        </p>
        <pre class="programlisting">    environment myenv {
        database data_one {
            type btree
        }
        database data_two {
            type btree
        }
        database data_three {
            type btree
        }
    } </pre>
        <p>
            In this case, the public <a class="link" href="db.html" title="Chapter 2.  The DB Handle">DB</a> handles would be:
        </p>
        <pre class="programlisting">    DB_ENV  *myenv_dbenv;
    DB      *myenv_data_one;
    DB      *myenv_data_two;
    DB      *myenv_data_three; </pre>
        <p>
            A variety of keywords can be specified for the databases and the environments. For
            example, the cache size can be specified for the database environment, and the page size
            can be specified for the database, as well as secondary relationships:
        </p>
        <pre class="programlisting">    environment myenv {
        cachesize 2 0 10
        database data_one {
            type btree
            pagesize 1024
        }
        database data_two {
            primary data_one
            secondary_offset 10 15
            type btree
            pagesize 32768
        }
        database data_three {
            type btree
            pagesize 512
        }
    } </pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1713874"></a>Environment Keywords</h3>
            </div>
          </div>
        </div>
        <p>
            The following are the keywords that you use to configure database environments:
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    <code class="literal">environment</code>
                </p>
              <p>
                    Start a database environment block. 
                </p>
              <p>
                    There must be three tokens on the line: the keyword, the name of the environment
                    and an opening brace (<code class="literal">{</code>).
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">home</code>
                </p>
              <p>
                    Specify the database environment home directory. 
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the home directory.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">cachesize</code>
                </p>
              <p>
                    Specify the database environment cache size.
                </p>
              <p>
                    There must be four tokens on the line: the keyword, the gigabytes of cache, the
                    bytes of cache, and the number of caches (the number of underlying physical
                    areas into which the cache is logically divided).
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">private</code>
                </p>
              <p>
                    Specify the database environment is private. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">}</code>
                </p>
              <p>
                    End the database environment block. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
          </ul>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="id1714213"></a>Database Keywords</h3>
            </div>
          </div>
        </div>
        <p>
            The following keywords are used to configure databases.
        </p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>
              <p>
                    <code class="literal">database</code>
                </p>
              <p>
                    Start a database block. 
                </p>
              <p>
                    There must be three tokens on the line: the keyword, the name of the database
                    and an opening brace (<code class="literal">{</code>).
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">custom</code>
                </p>
              <p>
                    Specify a custom key-comparison routine. This is used when the Btree database
                    requires a specific sort that db_codegen cannot generate. A stub key comparison
                    routine will be created and configured for the database which should be modified
                    as necessary. See the "key_type" keyword for more information. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">dupsort</code>
                </p>
              <p>
                    Configure the database to support sorted duplicates. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">extentsize</code>
                </p>
              <p>
                    Configure the size of the Queue database extent files. 
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the extent file size, as
                    a number of pages.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">key_type</code>
                </p>
              <p>
                    Configure a integral type key-comparison routine. This is used when the Btree
                    database Btree database key is an integral type (such as "unsigned int", or
                    "u_int32_t"). Any C-language integral type may be specified. See the "custom"
                    keyword for more information. A Btree comparison routine based on the type of
                    the key will be created and configured.
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the type.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">pagesize</code>
                </p>
              <p>
                    Configure the database page size. 
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the page size in bytes.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">primary</code>
                </p>
              <p>
                    Configure the database as a secondary index. A stub secondary callback routine
                    will be created and configured for the database, which should be modified as
                    necessary. See the "secondary_offset" keyword for more information.
                </p>
              <p>
                    There must be two tokens on the line: the keyword and the name of the primary database 
                    for which this database is a secondary.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">recnum</code>
                </p>
              <p>
                    Configure the Btree database to support record number access. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">re_len</code>
                </p>
              <p>
                    Configure the record length for a Queue database or a fixed-length Recno
                    database. 
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the length of a record,
                    in bytes.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">secondary_offset</code>
                </p>
              <p>
                    Configure a secondary callback routine based on a byte string found in the
                    primary database's data item. 
                </p>
              <p>
                    There must be three tokens on the line: the keyword, the byte offset from the
                    beginning of the primary data item where the secondary key begins, and the
                    length of the secondary key in bytes.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">transaction</code>
                </p>
              <p>
                    Configure the database (and, by extension, the database environment), to be
                    transactional.
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">type</code>
                </p>
              <p>
                    Configure the database type. 
                </p>
              <p>
                    There must be two tokens on the line: the keyword, and the type, where the type
                    is one of <code class="literal">btree</code>, <code class="literal">hash</code>,
                    <code class="literal">queue</code> or <code class="literal">recno</code>.
                </p>
            </li>
            <li>
              <p>
                    <code class="literal">}</code>
                </p>
              <p>
                    End the database environment block. 
                </p>
              <p>
                    There must be one token on the line: the keyword by itself.
                </p>
            </li>
          </ul>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="db_checkpoint.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="utilities.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="db_deadlock.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">db_checkpoint </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> db_deadlock</td>
        </tr>
      </table>
    </div>
  </body>
</html>
